home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / 13h_kit / pcx.doc < prev    next >
Text File  |  1991-07-04  |  9KB  |  225 lines
  1. >>>PCX.DOC
  2.  
  3. A. Copyright Information
  4.  
  5. Images.Hpp and Images.Cpp along with this document file are copyright
  6. 1991 by the Gamers Programming Workshop, GAMERS forum, Compuserve (GO GAMERS,
  7. section 11). The code and related document are free for use, distribution,
  8. and modification, provided the following conditions are met:
  9.  
  10.     1. no commercial use of this source code or documents is permitted.
  11.     2. no fee may be charged beyond disk duplication cost for any of this
  12.        material.
  13.     3. If the code is upgraded or modified a copy of the modification must
  14.        be uploaded to section 11 of the GAMERS forum on Compuserve. All
  15.        modifications must be documented and the author's name included in
  16.        the source code header block, and the subsequent file package must
  17.        include all the original doc files as well as any additions. If you
  18.        modify or add functions please update the function list below.
  19.  
  20.  
  21. B. Description
  22.  
  23. The IMAGES.HPP file provides the definition of a class image, from which
  24. is descended class pcx. Images is a base class containing information
  25. generic to any full screen image, such as where it's located on disk, where
  26. it's located in memory, what it's status is, etc. The descendent class, pcx,
  27. adds methods and data specific to the pcx class of images. It's expected that
  28. at some point new classes will be descended from images to accomodate other
  29. popular graphics formats.
  30.  
  31. The defintion of the images class is as follows:
  32.  
  33. class image {
  34.     public:
  35.     p_rec palette;                        // holds the default image palette
  36.     char fpath[80];                       // stores the disk path to image
  37.     char getstatus() {return(status);}    // returns status of last op
  38.                                           // see err codes in IMAGES.HPP
  39.     protected:
  40.     char in_ram;                          // 1 if image in ram, 0 if not
  41.     char packed;                          // 1 if packed in ram, 0 if not
  42.     char status;                          // returned by getstatus()
  43.     char far *buffer;                     // pointer for ram buffer if any
  44. };
  45.  
  46. This is the definition for the descendent pcx class:
  47.  
  48. class pcx : public image {
  49.     public:
  50.     pcx(char *fspec);                     // constructor
  51.     char load(char method);               // load into ram packed or unpacked
  52.     void unload();                        // unload from ram
  53.     char display(char fadetype);          // display image using fadetype
  54.     void remove(char fadetype);           // remove image using fadetype
  55.     ~pcx();                                  // destructor
  56.     private:
  57.     char unpacktoram(char far *dest,      // internal, unpack to memory
  58.                      unsigned numbytes);
  59.  
  60. };
  61.  
  62. C. Function interface.
  63.  
  64. *****************************************************************************
  65.  
  66. images::getstatus()
  67.  
  68. getstatus returns the current value of the status member variable. This var
  69. holds the result of operations executed in the constructor. All other methods
  70. explicitly return an error code if applicable. Call getstatus after declaring
  71. an instance of a pcx class object.
  72.  
  73. *****************************************************************************
  74.  
  75. pcx::pcx(char *fspec);
  76.  
  77. The constructor opens the file and determines if it is a valid 256 color
  78. mode 13h pcx file. If so, it loads the palette into the palette member
  79. structure, ignores the header (this can be easily changed if you need the
  80. header for something), and sets several object data members to initial
  81. values. It returns error codes as defined in IMAGES.HPP
  82.  
  83. *****************************************************************************
  84.  
  85. char pcx::load(char method);
  86.  
  87. load() attempts to get the image data from disk into memory in order to
  88. speed display. The method variable may have one of three values (constants
  89. defined in IMAGES.HPP). They are Packed, Unpacked, and Bestfit. Packed
  90. causes the data to be loaded into memory in compressed form. Unpacked causes
  91. the data to be decompressed to a memory buffer. Bestfit causes the function
  92. to determine if the data will be stored Packed or Unpacked based on avail-
  93. able memory. In any of these cases the function will return a MemErr if the
  94. minimum required memory is not available. If the load succeeds a pointer
  95. to the buffer will be stored in the buffer member variable for later use,
  96. and the in_ram and packed member variables will be updated to reflect the
  97. pcx object's status.
  98.  
  99. *****************************************************************************
  100.  
  101. void pcx::unload();
  102.  
  103. unload() removes the image data from memory, frees the buffer, and updates
  104. the values of the member status variables in_ram and packed. If the image
  105. is not loaded the function returns an UnknownErr.
  106.  
  107. *****************************************************************************
  108.  
  109. char pcx::display(char fadetype);
  110.  
  111. display() is the heart of the pcx class. It will cause the object to be disp-
  112. layed on screen regardless of it's current status. If the image is still on
  113. disk it will be displayed from there. Likewise if it is in ram packed or
  114. unpacked. The fadetype argument can have one of the constant values defined
  115. in IMAGES.HPP. Of the possible fades and dissolves all but SoftFade and
  116. SnapWipe require that the image data be in a 64000 byte memory buffer, un-
  117. packed. If this memory is not available and one of the other fades has been
  118. requested the function will return a MemErr. You can call display regardless
  119. of where the image is currently located. Display will be fastest if the
  120. image is located in ram unpacked, and slowest if the image is on disk. One
  121. possible method would be to use a load(Bestfit) call on a series of images,
  122. and then display them. In this case you do not have to check for available
  123. memory. The performance of the display calls will depend on how much memory
  124. is available at runtime.
  125.  
  126. *****************************************************************************
  127.  
  128. void pcx::remove(char fadetype);
  129.  
  130. remove() performs the opposite task of display(). It will blank the screen
  131. using the fade requested. No memory is required, no value is returned, and
  132. the status of the pcx object is not affected.
  133.  
  134. *****************************************************************************
  135.  
  136. pcx::~pcx();
  137.  
  138. The destructor frees any memory allocated to the image buffer, nulls all
  139. pointers and closes down the object.
  140.  
  141. *****************************************************************************
  142.  
  143. char pcx::unpacktoram(char far *dest, unsigned numbytes);
  144.  
  145. This is a private method used by the display and load functions to unpack
  146. the rle encoded pcx data. It can possibly return errorcodes for file errors.
  147. If it returns an error code to either display or load that function will
  148. return a SecondaryErr to it's caller.
  149.  
  150. *****************************************************************************
  151.  
  152. D. Example of useage
  153.  
  154. #include <dos.h>
  155. #include "images.hpp"
  156.  
  157. void main() {
  158.     char result;
  159.  
  160.     setgraphmode();
  161.  
  162.     // initialize three pcx objects with full error checking. Pcx files
  163.     // should be in the current directory.
  164.  
  165.     pcx pcx1("test1.pcx");
  166.     if (pcx1.getstatus() != NoErr) {
  167.         reporterr(pcx1.getstatus(),"object constructor");
  168.         return;
  169.     }
  170.     pcx pcx2("test2.pcx");
  171.     if (pcx2.getstatus() != NoErr) {
  172.         reporterr(pcx2.getstatus(),"object constructor");
  173.         return;
  174.     }
  175.     pcx pcx3("test3.pcx");
  176.     if (pcx3.getstatus() != NoErr) {
  177.         reporterr(pcx3.getstatus(),"object constructor");
  178.         return;
  179.     }
  180.  
  181.     // load the three files Bestfit. Ultimately we'd like them all in
  182.     // ram and unpacked to speed up the display.
  183.  
  184.     result = pcx1.load(Bestfit);
  185.     if ((result != NoErr) && (result != MemErr)) {
  186.         reporterr(result,"pcx1.load()");
  187.         return;
  188.     }
  189.     result = pcx2.load(Bestfit);
  190.     if ((result != NoErr) && (result != MemErr)) {
  191.         reporterr(result,"pcx2.load()");
  192.         return;
  193.     }
  194.     result = pcx3.load(Bestfit);
  195.     if ((result != NoErr) && (result != MemErr)) {
  196.         reporterr(result,"pcx3.load()");
  197.         return;
  198.     }
  199.  
  200.     // display the images using various fade types with a 1 second delay
  201.     // between successive images.
  202.  
  203.     pcx1.display(SoftFade);
  204.     delay(1000);
  205.     pcx1.remove(SplitHorizDissolve);
  206.     pcx2.display(SlideVerticalWipe);
  207.     delay(1000);
  208.     pcx2.remove(SoftFade);
  209.     pcx3.display(SplitVerticalDissolve);
  210.     delay(1000);
  211.     pcx3.remove(SnapWipe);
  212.  
  213.     settextmode();
  214.     return;
  215. }
  216.  
  217.  
  218.  
  219. E. Support
  220.  
  221. Support will be provided for this tool where and as possible through mess-
  222. ages posted to 76605,2346 in the Game Design section (sec. 11) of the Gamers
  223. Forum on Compuserve. Sorry, no telephone support is possible.
  224.  
  225.